SGI Freeware 1998 November/Freeware November 1998.img/dist/fw_elisp-manual-19.idb/usr/freeware/info/elisp-31.z/elisp-31

GNU Info File | 1998-05-26 | 50KB | 921 lines

This is Info file elisp, produced by Makeinfo-1.63 from the input file
elisp.texi.
   This version is the edition 2.4.2 of the GNU Emacs Lisp Reference
Manual.  It corresponds to Emacs Version 19.34.
   Published by the Free Software Foundation 59 Temple Place, Suite 330
Boston, MA  02111-1307  USA
   Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1996 Free Software
Foundation, Inc.
   Permission is granted to make and distribute verbatim copies of this
manual provided the copyright notice and this permission notice are
preserved on all copies.
   Permission is granted to copy and distribute modified versions of
this manual under the conditions for verbatim copying, provided that the
entire resulting derived work is distributed under the terms of a
permission notice identical to this one.
   Permission is granted to copy and distribute translations of this
manual into another language, under the above conditions for modified
versions, except that this permission notice may be stated in a
translation approved by the Foundation.
   Permission is granted to copy and distribute modified versions of
this manual under the conditions for verbatim copying, provided also
that the section entitled "GNU General Public License" is included
exactly as in the original, and provided that the entire resulting
derived work is distributed under the terms of a permission notice
identical to this one.
   Permission is granted to copy and distribute translations of this
manual into another language, under the above conditions for modified
versions, except that the section entitled "GNU General Public License"
may be included in a translation approved by the Free Software
Foundation instead of in the original English.
File: elisp,  Node: Output from Processes,  Next: Sentinels,  Prev: Signals to Processes,  Up: Processes
Receiving Output from Processes
===============================
   There are two ways to receive the output that a subprocess writes to
its standard output stream.  The output can be inserted in a buffer,
which is called the associated buffer of the process, or a function
called the "filter function" can be called to act on the output.  If
the process has no buffer and no filter function, its output is
discarded.
* Menu:
* Process Buffers::       If no filter, output is put in a buffer.
* Filter Functions::      Filter functions accept output from the process.
* Accepting Output::      Explicitly permitting subprocess output.
                            Waiting for subprocess output.
File: elisp,  Node: Process Buffers,  Next: Filter Functions,  Up: Output from Processes
Process Buffers
---------------
   A process can (and usually does) have an "associated buffer", which
is an ordinary Emacs buffer that is used for two purposes: storing the
output from the process, and deciding when to kill the process.  You
can also use the buffer to identify a process to operate on, since in
normal practice only one process is associated with any given buffer.
Many applications of processes also use the buffer for editing input to
be sent to the process, but this is not built into Emacs Lisp.
   Unless the process has a filter function (*note Filter Functions::.),
its output is inserted in the associated buffer.  The position to insert
the output is determined by the `process-mark', which is then updated
to point to the end of the text just inserted.  Usually, but not
always, the `process-mark' is at the end of the buffer.
 - Function: process-buffer PROCESS
     This function returns the associated buffer of the process PROCESS.
          (process-buffer (get-process "shell"))
               => #<buffer *shell*>
 - Function: process-mark PROCESS
     This function returns the process marker for PROCESS, which is the
     marker that says where to insert output from the process.
     If PROCESS does not have a buffer, `process-mark' returns a marker
     that points nowhere.
     Insertion of process output in a buffer uses this marker to decide
     where to insert, and updates it to point after the inserted text.
     That is why successive batches of output are inserted
     consecutively.
     Filter functions normally should use this marker in the same
     fashion as is done by direct insertion of output in the buffer.  A
     good example of a filter function that uses `process-mark' is
     found at the end of the following section.
     When the user is expected to enter input in the process buffer for
     transmission to the process, the process marker is useful for
     distinguishing the new input from previous output.
 - Function: set-process-buffer PROCESS BUFFER
     This function sets the buffer associated with PROCESS to BUFFER.
     If BUFFER is `nil', the process becomes associated with no buffer.
 - Function: get-buffer-process BUFFER-OR-NAME
     This function returns the process associated with BUFFER-OR-NAME.
     If there are several processes associated with it, then one is
     chosen.  (Presently, the one chosen is the one most recently
     created.)  It is usually a bad idea to have more than one process
     associated with the same buffer.
          (get-buffer-process "*shell*")
               => #<process shell>
     Killing the process's buffer deletes the process, which kills the
     subprocess with a `SIGHUP' signal (*note Signals to Processes::.).
File: elisp,  Node: Filter Functions,  Next: Accepting Output,  Prev: Process Buffers,  Up: Output from Processes
Process Filter Functions
------------------------
   A process "filter function" is a function that receives the standard
output from the associated process.  If a process has a filter, then
*all* output from that process is passed to the filter.  The process
buffer is used directly for output from the process only when there is
no filter.
   A filter function must accept two arguments: the associated process
and a string, which is the output.  The function is then free to do
whatever it chooses with the output.
   A filter function runs only while Emacs is waiting (e.g., for
terminal input, or for time to elapse, or for process output).  This
avoids the timing errors that could result from running filters at
random places in the middle of other Lisp programs.  You may explicitly
cause Emacs to wait, so that filter functions will run, by calling
`sit-for' or `sleep-for' (*note Waiting::.), or `accept-process-output'
(*note Accepting Output::.).  Emacs is also waiting when the command
loop is reading input.
   Quitting is normally inhibited within a filter function--otherwise,
the effect of typing `C-g' at command level or to quit a user command
would be unpredictable.  If you want to permit quitting inside a filter
function, bind `inhibit-quit' to `nil'.  *Note Quitting::.
   If an error happens during execution of a filter function, it is
caught automatically, so that it doesn't stop the execution of whatever
program was running when the filter function was started.  However, if
`debug-on-error' is non-`nil', the error-catching is turned off.  This
makes it possible to use the Lisp debugger to debug the filter
function.  *Note Debugger::.
   Many filter functions sometimes or always insert the text in the
process's buffer, mimicking the actions of Emacs when there is no
filter.  Such filter functions need to use `set-buffer' in order to be
sure to insert in that buffer.  To avoid setting the current buffer
semipermanently, these filter functions must use `unwind-protect' to
make sure to restore the previous current buffer.  They should also
update the process marker, and in some cases update the value of point.
Here is how to do these things:
     (defun ordinary-insertion-filter (proc string)
       (let ((old-buffer (current-buffer)))
         (unwind-protect
             (let (moving)
               (set-buffer (process-buffer proc))
               (setq moving (= (point) (process-mark proc)))
     (save-excursion
                 ;; Insert the text, moving the process-marker.
                 (goto-char (process-mark proc))
                 (insert string)
                 (set-marker (process-mark proc) (point)))
               (if moving (goto-char (process-mark proc))))
           (set-buffer old-buffer))))
The reason to use an explicit `unwind-protect' rather than letting
`save-excursion' restore the current buffer is so as to preserve the
change in point made by `goto-char'.
   To make the filter force the process buffer to be visible whenever
new text arrives, insert the following line just before the
`unwind-protect':
     (display-buffer (process-buffer proc))
   To force point to move to the end of the new output no matter where
it was previously, eliminate the variable `moving' and call `goto-char'
unconditionally.
   In earlier Emacs versions, every filter function that did regexp
searching or matching had to explicitly save and restore the match data.
Now Emacs does this automatically; filter functions never need to do it
explicitly.  *Note Match Data::.
   A filter function that writes the output into the buffer of the
process should check whether the buffer is still alive.  If it tries to
insert into a dead buffer, it will get an error.  If the buffer is dead,
`(buffer-name (process-buffer PROCESS))' returns `nil'.
   The output to the function may come in chunks of any size.  A program
that produces the same output twice in a row may send it as one batch
of 200 characters one time, and five batches of 40 characters the next.
 - Function: set-process-filter PROCESS FILTER
     This function gives PROCESS the filter function FILTER.  If FILTER
     is `nil', it gives the process no filter.
 - Function: process-filter PROCESS
     This function returns the filter function of PROCESS, or `nil' if
     it has none.
   Here is an example of use of a filter function:
     (defun keep-output (process output)
        (setq kept (cons output kept)))
          => keep-output
     (setq kept nil)
          => nil
     (set-process-filter (get-process "shell") 'keep-output)
          => keep-output
     (process-send-string "shell" "ls ~/other\n")
          => nil
     kept
          => ("lewis@slug[8] % "
     "FINAL-W87-SHORT.MSS    backup.otl              kolstad.mss~
     address.txt             backup.psf              kolstad.psf
     backup.bib~             david.mss               resume-Dec-86.mss~
     backup.err              david.psf               resume-Dec.psf
     backup.mss              dland                   syllabus.mss
     "
     "#backups.mss#          backup.mss~             kolstad.mss
     ")
File: elisp,  Node: Accepting Output,  Prev: Filter Functions,  Up: Output from Processes
Accepting Output from Processes
-------------------------------
   Output from asynchronous subprocesses normally arrives only while
Emacs is waiting for some sort of external event, such as elapsed time
or terminal input.  Occasionally it is useful in a Lisp program to
explicitly permit output to arrive at a specific point, or even to wait
until output arrives from a process.
 - Function: accept-process-output &optional PROCESS SECONDS MILLISEC
     This function allows Emacs to read pending output from processes.
     The output is inserted in the associated buffers or given to their
     filter functions.  If PROCESS is non-`nil' then this function does
     not return until some output has been received from PROCESS.
     The arguments SECONDS and MILLISEC let you specify timeout
     periods.  The former specifies a period measured in seconds and the
     latter specifies one measured in milliseconds.  The two time
     periods thus specified are added together, and
     `accept-process-output' returns after that much time whether or
     not there has been any subprocess output.
     The argument SECONDS need not be an integer.  If it is a floating
     point number, this function waits for a fractional number of
     seconds.  Some systems support only a whole number of seconds; on
     these systems, SECONDS is rounded down.  If the system doesn't
     support waiting fractions of a second, you get an error if you
     specify nonzero MILLISEC.
     Not all operating systems support waiting periods other than
     multiples of a second; on those that do not, you get an error if
     you specify nonzero MILLISEC.
     The function `accept-process-output' returns non-`nil' if it did
     get some output, or `nil' if the timeout expired before output
     arrived.
File: elisp,  Node: Sentinels,  Next: Transaction Queues,  Prev: Output from Processes,  Up: Processes
Sentinels: Detecting Process Status Changes
===========================================
   A "process sentinel" is a function that is called whenever the
associated process changes status for any reason, including signals
(whether sent by Emacs or caused by the process's own actions) that
terminate, stop, or continue the process.  The process sentinel is also
called if the process exits.  The sentinel receives two arguments: the
process for which the event occurred, and a string describing the type
of event.
   The string describing the event looks like one of the following:
   * `"finished\n"'.
   * `"exited abnormally with code EXITCODE\n"'.
   * `"NAME-OF-SIGNAL\n"'.
   * `"NAME-OF-SIGNAL (core dumped)\n"'.
   A sentinel runs only while Emacs is waiting (e.g., for terminal
input, or for time to elapse, or for process output).  This avoids the
timing errors that could result from running them at random places in
the middle of other Lisp programs.  A program can wait, so that
sentinels will run, by calling `sit-for' or `sleep-for' (*note
Waiting::.), or `accept-process-output' (*note Accepting Output::.).
Emacs is also waiting when the command loop is reading input.
   Quitting is normally inhibited within a sentinel--otherwise, the
effect of typing `C-g' at command level or to quit a user command would
be unpredictable.  If you want to permit quitting inside a sentinel,
bind `inhibit-quit' to `nil'.  *Note Quitting::.
   A sentinel that writes the output into the buffer of the process
should check whether the buffer is still alive.  If it tries to insert
into a dead buffer, it will get an error.  If the buffer is dead,
`(buffer-name (process-buffer PROCESS))' returns `nil'.
   If an error happens during execution of a sentinel, it is caught
automatically, so that it doesn't stop the execution of whatever
programs was running when the sentinel was started.  However, if
`debug-on-error' is non-`nil', the error-catching is turned off.  This
makes it possible to use the Lisp debugger to debug the sentinel.
*Note Debugger::.
   In earlier Emacs versions, every sentinel that did regexp searching
or matching had to explicitly save and restore the match data.  Now
Emacs does this automatically; sentinels never need to do it explicitly.
*Note Match Data::.
 - Function: set-process-sentinel PROCESS SENTINEL
     This function associates SENTINEL with PROCESS.  If SENTINEL is
     `nil', then the process will have no sentinel.  The default
     behavior when there is no sentinel is to insert a message in the
     process's buffer when the process status changes.
          (defun msg-me (process event)
             (princ
               (format "Process: %s had the event `%s'" process event)))
          (set-process-sentinel (get-process "shell") 'msg-me)
               => msg-me
          (kill-process (get-process "shell"))
               -| Process: #<process shell> had the event `killed'
               => #<process shell>
 - Function: process-sentinel PROCESS
     This function returns the sentinel of PROCESS, or `nil' if it has
     none.
 - Function: waiting-for-user-input-p
     While a sentinel or filter function is running, this function
     returns non-`nil' if Emacs was waiting for keyboard input from the
     user at the time the sentinel or filter function was called, `nil'
     if it was not.
File: elisp,  Node: Transaction Queues,  Next: Network,  Prev: Sentinels,  Up: Processes
Transaction Queues
==================
   You can use a "transaction queue" for more convenient communication
with subprocesses using transactions.  First use `tq-create' to create
a transaction queue communicating with a specified process.  Then you
can call `tq-enqueue' to send a transaction.
 - Function: tq-create PROCESS
     This function creates and returns a transaction queue
     communicating with PROCESS.  The argument PROCESS should be a
     subprocess capable of sending and receiving streams of bytes.  It
     may be a child process, or it may be a TCP connection to a server,
     possibly on another machine.
 - Function: tq-enqueue QUEUE QUESTION REGEXP CLOSURE FN
     This function sends a transaction to queue QUEUE.  Specifying the
     queue has the effect of specifying the subprocess to talk to.
     The argument QUESTION is the outgoing message that starts the
     transaction.  The argument FN is the function to call when the
     corresponding answer comes back; it is called with two arguments:
     CLOSURE, and the answer received.
     The argument REGEXP is a regular expression that should match the
     entire answer, but nothing less; that's how `tq-enqueue' determines
     where the answer ends.
     The return value of `tq-enqueue' itself is not meaningful.
 - Function: tq-close QUEUE
     Shut down transaction queue QUEUE, waiting for all pending
     transactions to complete, and then terminate the connection or
     child process.
   Transaction queues are implemented by means of a filter function.
*Note Filter Functions::.
File: elisp,  Node: Network,  Prev: Transaction Queues,  Up: Processes
Network Connections
===================
   Emacs Lisp programs can open TCP network connections to other
processes on the same machine or other machines.  A network connection
is handled by Lisp much like a subprocess, and is represented by a
process object.  However, the process you are communicating with is not
a child of the Emacs process, so you can't kill it or send it signals.
All you can do is send and receive data.  `delete-process' closes the
connection, but does not kill the process at the other end; that
process must decide what to do about closure of the connection.
   You can distinguish process objects representing network connections
from those representing subprocesses with the `process-status'
function.  It always returns either `open' or `closed' for a network
connection, and it never returns either of those values for a real
subprocess.  *Note Process Information::.
 - Function: open-network-stream NAME BUFFER-OR-NAME HOST SERVICE
     This function opens a TCP connection for a service to a host.  It
     returns a process object to represent the connection.
     The NAME argument specifies the name for the process object.  It
     is modified as necessary to make it unique.
     The BUFFER-OR-NAME argument is the buffer to associate with the
     connection.  Output from the connection is inserted in the buffer,
     unless you specify a filter function to handle the output.  If
     BUFFER-OR-NAME is `nil', it means that the connection is not
     associated with any buffer.
     The arguments HOST and SERVICE specify where to connect to; HOST
     is the host name (a string), and SERVICE is the name of a defined
     network service (a string) or a port number (an integer).
File: elisp,  Node: System Interface,  Next: Display,  Prev: Processes,  Up: Top
Operating System Interface
**************************
   This chapter is about starting and getting out of Emacs, access to
values in the operating system environment, and terminal input, output,
and flow control.
   *Note Building Emacs::, for related information.  See also *Note
Display::, for additional operating system status information
pertaining to the terminal and the screen.
* Menu:
* Starting Up::         Customizing Emacs start-up processing.
* Getting Out::         How exiting works (permanent or temporary).
* System Environment::  Distinguish the name and kind of system.
* User Identification:: Finding the name and user id of the user.
* Time of Day::        Getting the current time.
* Time Conversion::     Converting a time from numeric form to a string, or
                          to calendrical data (or vice versa).
* Timers::        Setting a timer to call a function at a certain time.
* Terminal Input::      Recording terminal input for debugging.
* Terminal Output::     Recording terminal output for debugging.
* Special Keysyms::     Defining system-specific key symbols for X windows.
* Flow Control::        How to turn output flow control on or off.
* Batch Mode::          Running Emacs without terminal interaction.
File: elisp,  Node: Starting Up,  Next: Getting Out,  Up: System Interface
Starting Up Emacs
=================
   This section describes what Emacs does when it is started, and how
you can customize these actions.
* Menu:
* Start-up Summary::        Sequence of actions Emacs performs at start-up.
* Init File::               Details on reading the init file (`.emacs').
* Terminal-Specific::       How the terminal-specific Lisp file is read.
* Command Line Arguments::  How command line arguments are processed,
                              and how you can customize them.
File: elisp,  Node: Start-up Summary,  Next: Init File,  Up: Starting Up
Summary: Sequence of Actions at Start Up
----------------------------------------
   The order of operations performed (in `startup.el') by Emacs when it
is started up is as follows:
  1. It loads the initialization library for the window system, if you
     are using a window system.  This library's name is
     `term/WINDOWSYSTEM-win.el'.
  2. It processes the initial options.  (Some of them are handled even
     earlier than this.)
  3. It initializes the X window frame and faces, if appropriate.
  4. It runs the normal hook `before-init-hook'.
  5. It loads the library `site-start', unless the option
     `-no-site-file' was specified.  The library's file name is usually
     `site-start.el'.
  6. It loads the file `~/.emacs' unless `-q' was specified on the
     command line.  (This is not done in `-batch' mode.)  The `-u'
     option can specify the user name whose home directory should be
     used instead of `~'.
  7. It loads the library `default' unless `inhibit-default-init' is
     non-`nil'.  (This is not done in `-batch' mode or if `-q' was
     specified on the command line.)  The library's file name is
     usually `default.el'.
  8. It runs the normal hook `after-init-hook'.
  9. It sets the major mode according to `initial-major-mode', provided
     the buffer `*scratch*' is still current and still in Fundamental
     mode.
 10. It loads the terminal-specific Lisp file, if any, except when in
     batch mode or using a window system.
 11. It displays the initial echo area message, unless you have
     suppressed that with `inhibit-startup-echo-area-message'.
 12. It processes the action arguments from the command line.
 13. It runs `term-setup-hook'.
 14. It calls `frame-notice-user-settings', which modifies the
     parameters of the selected frame according to whatever the init
     files specify.
 15. It runs `window-setup-hook'.  *Note Window Systems::.
 16. It displays copyleft, nonwarranty, and basic use information,
     provided there were no remaining command line arguments (a few
     steps above) and the value of `inhibit-startup-message' is `nil'.
 - User Option: inhibit-startup-message
     This variable inhibits the initial startup messages (the
     nonwarranty, etc.).  If it is non-`nil', then the messages are not
     printed.
     This variable exists so you can set it in your personal init file,
     once you are familiar with the contents of the startup message.
     Do not set this variable in the init file of a new user, or in a
     way that affects more than one user, because that would prevent
     new users from receiving the information they are supposed to see.
 - User Option: inhibit-startup-echo-area-message
     This variable controls the display of the startup echo area
     message.  You can suppress the startup echo area message by adding
     text with this form to your `.emacs' file:
          (setq inhibit-startup-echo-area-message
                "YOUR-LOGIN-NAME")
     Simply setting `inhibit-startup-echo-area-message' to your login
     name is not sufficient to inhibit the message; Emacs explicitly
     checks whether `.emacs' contains an expression as shown above.
     Your login name must appear in the expression as a Lisp string
     constant.
     This way, you can easily inhibit the message for yourself if you
     wish, but thoughtless copying of your `.emacs' file will not
     inhibit the message for someone else.
File: elisp,  Node: Init File,  Next: Terminal-Specific,  Prev: Start-up Summary,  Up: Starting Up
The Init File: `.emacs'
-----------------------
   When you start Emacs, it normally attempts to load the file `.emacs'
from your home directory.  This file, if it exists, must contain Lisp
code.  It is called your "init file".  The command line switches `-q'
and `-u' affect the use of the init file; `-q' says not to load an init
file, and `-u' says to load a specified user's init file instead of
yours.  *Note Entering Emacs: (emacs)Entering Emacs.
   A site may have a "default init file", which is the library named
`default.el'.  Emacs finds the `default.el' file through the standard
search path for libraries (*note How Programs Do Loading::.).  The
Emacs distribution does not come with this file; sites may provide one
for local customizations.  If the default init file exists, it is
loaded whenever you start Emacs, except in batch mode or if `-q' is
specified.  But your own personal init file, if any, is loaded first; if
it sets `inhibit-default-init' to a non-`nil' value, then Emacs does
not subsequently load the `default.el' file.
   Another file for site-customization is `site-start.el'.  Emacs loads
this *before* the user's init file.  You can inhibit the loading of
this file with the option `-no-site-file'.
 - Variable: site-run-file
     This variable specifies the site-customization file to load before
     the user's init file.  Its normal value is `"site-start"'.
   If there is a great deal of code in your `.emacs' file, you should
move it into another file named `SOMETHING.el', byte-compile it (*note
Byte Compilation::.), and make your `.emacs' file load the other file
using `load' (*note Loading::.).
   *Note Init File Examples: (emacs)Init File Examples, for examples of
how to make various commonly desired customizations in your `.emacs'
file.
 - User Option: inhibit-default-init
     This variable prevents Emacs from loading the default
     initialization library file for your session of Emacs.  If its
     value is non-`nil', then the default library is not loaded.  The
     default value is `nil'.
 - Variable: before-init-hook
 - Variable: after-init-hook
     These two normal hooks are run just before, and just after,
     loading of the user's init file, `default.el', and/or
     `site-start.el'.
File: elisp,  Node: Terminal-Specific,  Next: Command Line Arguments,  Prev: Init File,  Up: Starting Up
Terminal-Specific Initialization
--------------------------------
   Each terminal type can have its own Lisp library that Emacs loads
when run on that type of terminal.  For a terminal type named TERMTYPE,
the library is called `term/TERMTYPE'.  Emacs finds the file by
searching the `load-path' directories as it does for other files, and
trying the `.elc' and `.el' suffixes.  Normally, terminal-specific Lisp
library is located in `emacs/lisp/term', a subdirectory of the
`emacs/lisp' directory in which most Emacs Lisp libraries are kept.
   The library's name is constructed by concatenating the value of the
variable `term-file-prefix' and the terminal type.  Normally,
`term-file-prefix' has the value `"term/"'; changing this is not
recommended.
   The usual function of a terminal-specific library is to enable
special keys to send sequences that Emacs can recognize.  It may also
need to set or add to `function-key-map' if the Termcap entry does not
specify all the terminal's function keys.  *Note Terminal Input::.
   When the name of the terminal type contains a hyphen, only the part
of the name before the first hyphen is significant in choosing the
library name.  Thus, terminal types `aaa-48' and `aaa-30-rv' both use
the `term/aaa' library.  If necessary, the library can evaluate
`(getenv "TERM")' to find the full name of the terminal type.
   Your `.emacs' file can prevent the loading of the terminal-specific
library by setting the variable `term-file-prefix' to `nil'.  This
feature is useful when experimenting with your own peculiar
customizations.
   You can also arrange to override some of the actions of the
terminal-specific library by setting the variable `term-setup-hook'.
This is a normal hook which Emacs runs using `run-hooks' at the end of
Emacs initialization, after loading both your `.emacs' file and any
terminal-specific libraries.  You can use this variable to define
initializations for terminals that do not have their own libraries.
*Note Hooks::.
 - Variable: term-file-prefix
     If the `term-file-prefix' variable is non-`nil', Emacs loads a
     terminal-specific initialization file as follows:
          (load (concat term-file-prefix (getenv "TERM")))
     You may set the `term-file-prefix' variable to `nil' in your
     `.emacs' file if you do not wish to load the
     terminal-initialization file.  To do this, put the following in
     your `.emacs' file: `(setq term-file-prefix nil)'.
 - Variable: term-setup-hook
     This variable is a normal hook that Emacs runs after loading your
     `.emacs' file, the default initialization file (if any) and the
     terminal-specific Lisp file.
     You can use `term-setup-hook' to override the definitions made by a
     terminal-specific file.
   See `window-setup-hook' in *Note Window Systems::, for a related
feature.
File: elisp,  Node: Command Line Arguments,  Prev: Terminal-Specific,  Up: Starting Up
Command Line Arguments
----------------------
   You can use command line arguments to request various actions when
you start Emacs.  Since you do not need to start Emacs more than once
per day, and will often leave your Emacs session running longer than
that, command line arguments are hardly ever used.  As a practical
matter, it is best to avoid making the habit of using them, since this
habit would encourage you to kill and restart Emacs unnecessarily
often.  These options exist for two reasons: to be compatible with
other editors (for invocation by other programs) and to enable shell
scripts to run specific Lisp programs.
   This section describes how Emacs processes command line arguments,
and how you can customize them.
 - Function: command-line
     This function parses the command line that Emacs was called with,
     processes it, loads the user's `.emacs' file and displays the
     startup messages.
 - Variable: command-line-processed
     The value of this variable is `t' once the command line has been
     processed.
     If you redump Emacs by calling `dump-emacs', you may wish to set
     this variable to `nil' first in order to cause the new dumped Emacs
     to process its new command line arguments.
 - Variable: command-switch-alist
     The value of this variable is an alist of user-defined command-line
     options and associated handler functions.  This variable exists so
     you can add elements to it.
     A "command line option" is an argument on the command line of the
     form:
          -OPTION
     The elements of the `command-switch-alist' look like this:
          (OPTION . HANDLER-FUNCTION)
     The HANDLER-FUNCTION is called to handle OPTION and receives the
     option name as its sole argument.
     In some cases, the option is followed in the command line by an
     argument.  In these cases, the HANDLER-FUNCTION can find all the
     remaining command-line arguments in the variable
     `command-line-args-left'.  (The entire list of command-line
     arguments is in `command-line-args'.)
     The command line arguments are parsed by the `command-line-1'
     function in the `startup.el' file.  See also *Note Command Line
     Switches and Arguments: (emacs)Command Switches.
 - Variable: command-line-args
     The value of this variable is the list of command line arguments
     passed to Emacs.
 - Variable: command-line-functions
     This variable's value is a list of functions for handling an
     unrecognized command-line argument.  Each time the next argument
     to be processed has no special meaning, the functions in this list
     are called, in order of appearance, until one of them returns a
     non-`nil' value.
     These functions are called with no arguments.  They can access the
     command-line argument under consideration through the variable
     `argi'.  The remaining arguments (not including the current one)
     are in the variable `command-line-args-left'.
     When a function recognizes and processes the argument in `argi', it
     should return a non-`nil' value to say it has dealt with that
     argument.  If it has also dealt with some of the following
     arguments, it can indicate that by deleting them from
     `command-line-args-left'.
     If all of these functions return `nil', then the argument is used
     as a file name to visit.
File: elisp,  Node: Getting Out,  Next: System Environment,  Prev: Starting Up,  Up: System Interface
Getting Out of Emacs
====================
   There are two ways to get out of Emacs: you can kill the Emacs job,
which exits permanently, or you can suspend it, which permits you to
reenter the Emacs process later.  As a practical matter, you seldom kill
Emacs--only when you are about to log out.  Suspending is much more
common.
* Menu:
* Killing Emacs::        Exiting Emacs irreversibly.
* Suspending Emacs::     Exiting Emacs reversibly.
File: elisp,  Node: Killing Emacs,  Next: Suspending Emacs,  Up: Getting Out
Killing Emacs
-------------
   Killing Emacs means ending the execution of the Emacs process.  The
parent process normally resumes control.  The low-level primitive for
killing Emacs is `kill-emacs'.
 - Function: kill-emacs &optional EXIT-DATA
     This function exits the Emacs process and kills it.
     If EXIT-DATA is an integer, then it is used as the exit status of
     the Emacs process.  (This is useful primarily in batch operation;
     see *Note Batch Mode::.)
     If EXIT-DATA is a string, its contents are stuffed into the
     terminal input buffer so that the shell (or whatever program next
     reads input) can read them.
   All the information in the Emacs process, aside from files that have
been saved, is lost when the Emacs is killed.  Because killing Emacs
inadvertently can lose a lot of work, Emacs queries for confirmation
before actually terminating if you have buffers that need saving or
subprocesses that are running.  This is done in the function
`save-buffers-kill-emacs'.
 - Variable: kill-emacs-query-functions
     After asking the standard questions, `save-buffers-kill-emacs'
     calls the functions in the list `kill-buffer-query-functions', in
     order of appearance, with no arguments.  These functions can ask
     for additional confirmation from the user.  If any of them returns
     non-`nil', Emacs is not killed.
 - Variable: kill-emacs-hook
     This variable is a normal hook; once `save-buffers-kill-emacs' is
     finished with all file saving and confirmation, it runs the
     functions in this hook.
File: elisp,  Node: Suspending Emacs,  Prev: Killing Emacs,  Up: Getting Out
Suspending Emacs
----------------
   "Suspending Emacs" means stopping Emacs temporarily and returning
control to its superior process, which is usually the shell.  This
allows you to resume editing later in the same Emacs process, with the
same buffers, the same kill ring, the same undo history, and so on.  To
resume Emacs, use the appropriate command in the parent shell--most
likely `fg'.
   Some operating systems do not support suspension of jobs; on these
systems, "suspension" actually creates a new shell temporarily as a
subprocess of Emacs.  Then you would exit the shell to return to Emacs.
   Suspension is not useful with window systems such as X, because the
Emacs job may not have a parent that can resume it again, and in any
case you can give input to some other job such as a shell merely by
moving to a different window.  Therefore, suspending is not allowed
when Emacs is an X client.
 - Function: suspend-emacs STRING
     This function stops Emacs and returns control to the superior
     process.  If and when the superior process resumes Emacs,
     `suspend-emacs' returns `nil' to its caller in Lisp.
     If STRING is non-`nil', its characters are sent to be read as
     terminal input by Emacs's superior shell.  The characters in
     STRING are not echoed by the superior shell; only the results
     appear.
     Before suspending, `suspend-emacs' runs the normal hook
     `suspend-hook'.  In Emacs version 18, `suspend-hook' was not a
     normal hook; its value was a single function, and if its value was
     non-`nil', then `suspend-emacs' returned immediately without
     actually suspending anything.
     After the user resumes Emacs, `suspend-emacs' runs the normal hook
     `suspend-resume-hook'.  *Note Hooks::.
     The next redisplay after resumption will redraw the entire screen,
     unless the variable `no-redraw-on-reenter' is non-`nil' (*note
     Refresh Screen::.).
     In the following example, note that `pwd' is not echoed after
     Emacs is suspended.  But it is read and executed by the shell.
          (suspend-emacs)
               => nil
          (add-hook 'suspend-hook
                    (function (lambda ()
                                (or (y-or-n-p
                                      "Really suspend? ")
                                    (error "Suspend cancelled")))))
               => (lambda nil
                    (or (y-or-n-p "Really suspend? ")
                        (error "Suspend cancelled")))
          (add-hook 'suspend-resume-hook
                    (function (lambda () (message "Resumed!"))))
               => (lambda nil (message "Resumed!"))
          (suspend-emacs "pwd")
               => nil
          ---------- Buffer: Minibuffer ----------
          Really suspend? `y'
          ---------- Buffer: Minibuffer ----------
          ---------- Parent Shell ----------
          lewis@slug[23] % /user/lewis/manual
          lewis@slug[24] % fg
          ---------- Echo Area ----------
          Resumed!
 - Variable: suspend-hook
     This variable is a normal hook run before suspending.
 - Variable: suspend-resume-hook
     This variable is a normal hook run after suspending.
File: elisp,  Node: System Environment,  Next: User Identification,  Prev: Getting Out,  Up: System Interface
Operating System Environment
============================
   Emacs provides access to variables in the operating system
environment through various functions.  These variables include the
name of the system, the user's UID, and so on.
 - Variable: system-type
     The value of this variable is a symbol indicating the type of
     operating system Emacs is operating on.  Here is a table of the
     possible values:
    `aix-v3'
          AIX.
    `berkeley-unix'
          Berkeley BSD.
    `dgux'
          Data General DGUX operating system.
    `gnu'
          A GNU system (using the GNU kernel, which consists of the
          HURD and Mach).
    `gnu/linux'
          A variant GNU system using the Linux kernel.
    `hpux'
          Hewlett-Packard HPUX operating system.
    `irix'
          Silicon Graphics Irix system.
    `ms-dos'
          Microsoft MS-DOS "operating system."
    `next-mach'
          NeXT Mach-based system.
    `rtu'
          Masscomp RTU, UCB universe.
    `unisoft-unix'
          UniSoft UniPlus.
    `usg-unix-v'
          AT&T System V.
    `vax-vms'
          VAX VMS.
    `windows-nt'
          Microsoft windows NT.
    `xenix'
          SCO Xenix 386.
     We do not wish to add new symbols to make finer distinctions
     unless it is absolutely necessary!  In fact, we hope to eliminate
     some of these alternatives in the future.  We recommend using
     `system-configuration' to distinguish between different operating
     systems.
 - Variable: system-configuration
     This variable holds the three-part configuration name for the
     hardware/software configuration of your system, as a string.  The
     convenient way to test parts of this string is with `string-match'.
 - Function: system-name
     This function returns the name of the machine you are running on.
          (system-name)
               => "prep.ai.mit.edu"
   The symbol `system-name' is a variable as well as a function.  In
fact, the function returns whatever value the variable `system-name'
currently holds.  Thus, you can set the variable `system-name' in case
Emacs is confused about the name of your system.  The variable is also
useful for constructing frame titles (*note Frame Titles::.).
 - Variable: mail-host-address
     If this variable is non-`nil', it is used instead of `system-name'
     for purposes of generating email addresses.  For example, it is
     used when constructing the default value of `user-mail-address'.
     *Note User Identification::.  (Since this is done when Emacs
     starts up, the value actually used is the one saved when Emacs was
     dumped.  *Note Building Emacs::.)
 - Function: getenv VAR
     This function returns the value of the environment variable VAR,
     as a string.  Within Emacs, the environment variable values are
     kept in the Lisp variable `process-environment'.
          (getenv "USER")
               => "lewis"

          lewis@slug[10] % printenv
          PATH=.:/user/lewis/bin:/usr/bin:/usr/local/bin
          USER=lewis
          TERM=ibmapa16
          SHELL=/bin/csh
          HOME=/user/lewis
 - Command: setenv VARIABLE VALUE
     This command sets the value of the environment variable named
     VARIABLE to VALUE.  Both arguments should be strings.  This
     function works by modifying `process-environment'; binding that
     variable with `let' is also reasonable practice.
 - Variable: process-environment
     This variable is a list of strings, each describing one environment
     variable.  The functions `getenv' and `setenv' work by means of
     this variable.
          process-environment
          => ("l=/usr/stanford/lib/gnuemacs/lisp"
              "PATH=.:/user/lewis/bin:/usr/class:/nfsusr/local/bin"
              "USER=lewis"
          "TERM=ibmapa16"
              "SHELL=/bin/csh"
              "HOME=/user/lewis")
 - Variable: path-separator
     This variable holds a string which says which character separates
     directories in a search path (as found in an environment
     variable).  Its value is `":"' for Unix and GNU systems, and `";"'
     for MS-DOS and Windows NT.
 - Variable: invocation-name
     This variable holds the program name under which Emacs was
     invoked.  The value is a string, and does not include a directory
     name.
 - Variable: invocation-directory
     This variable holds the directory from which the Emacs executable
     was invoked, or perhaps `nil' if that directory cannot be
     determined.
 - Variable: installation-directory
     If non-`nil', this is a directory within which to look for the
     `lib-src' and `etc' subdirectories.  This is non-`nil' when Emacs
     can't find those directories in their standard installed
     locations, but can find them in a directory related somehow to the
     one containing the Emacs executable.
 - Function: load-average
     This function returns the current 1-minute, 5-minute and 15-minute
     load averages in a list.  The values are integers that are 100
     times the system load averages.  (The load averages indicate the
     number of processes trying to run.)
          (load-average)
               => (169 48 36)

          lewis@rocky[5] % uptime
           11:55am  up 1 day, 19:37,  3 users,
           load average: 1.69, 0.48, 0.36
 - Function: emacs-pid
     This function returns the process ID of the Emacs process.
 - Function: setprv PRIVILEGE-NAME &optional SETP GETPRV
     This function sets or resets a VMS privilege.  (It does not exist
     on Unix.)  The first arg is the privilege name, as a string.  The
     second argument, SETP, is `t' or `nil', indicating whether the
     privilege is to be turned on or off.  Its default is `nil'.  The
     function returns `t' if successful, `nil' otherwise.
     If the third argument, GETPRV, is non-`nil', `setprv' does not
     change the privilege, but returns `t' or `nil' indicating whether
     the privilege is currently enabled.
File: elisp,  Node: User Identification,  Next: Time of Day,  Prev: System Environment,  Up: System Interface
User Identification
===================
 - Variable: user-mail-address
     This holds the nominal email address of the user who is using
     Emacs.  Emacs normally sets this variable to a default value after
     reading your init files, but not if you have already set it.  So
     you can set the variable to some other value in your `~/.emacs'
     file if you do not want to use the default value.
 - Function: user-login-name &optional UID
     If you don't specify UID, this function returns the name under
     which the user is logged in.  If the environment variable `LOGNAME'
     is set, that value is used.  Otherwise, if the environment variable
     `USER' is set, that value is used.  Otherwise, the value is based
     on the effective UID, not the real UID.
     If you specify UID, the value is the user name that corresponds to
     UID (which should be an integer).
          (user-login-name)
               => "lewis"
 - Function: user-real-login-name
     This function returns the user name corresponding to Emacs's real
     UID.  This ignores the effective UID and ignores the environment
     variables `LOGNAME' and `USER'.
 - Function: user-full-name
     This function returns the full name of the user.
          (user-full-name)
               => "Bil Lewis"
   The symbols `user-login-name', `user-real-login-name' and
`user-full-name' are variables as well as functions.  The functions
return the same values that the variables hold.  These variables allow
you to "fake out" Emacs by telling the functions what to return.  The
variables are also useful for constructing frame titles (*note Frame
Titles::.).
 - Function: user-real-uid
     This function returns the real UID of the user.
          (user-real-uid)
               => 19
 - Function: user-uid
     This function returns the effective UID of the user.
File: elisp,  Node: Time of Day,  Next: Time Conversion,  Prev: User Identification,  Up: System Interface
Time of Day
===========
   This section explains how to determine the current time and the time
zone.
 - Function: current-time-string &optional TIME-VALUE
     This function returns the current time and date as a
     humanly-readable string.  The format of the string is unvarying;
     the number of characters used for each part is always the same, so
     you can reliably use `substring' to extract pieces of it.  It is
     wise to count the characters from the beginning of the string
     rather than from the end, as additional information may be added
     at the end.
     The argument TIME-VALUE, if given, specifies a time to format
     instead of the current time.  The argument should be a list whose
     first two elements are integers.  Thus, you can use times obtained
     from `current-time' (see below) and from `file-attributes' (*note
     File Attributes::.).
          (current-time-string)
               => "Wed Oct 14 22:21:05 1987"
 - Function: current-time
     This function returns the system's time value as a list of three
     integers: `(HIGH LOW MICROSEC)'.  The integers HIGH and LOW
     combine to give the number of seconds since 0:00 January 1, 1970,
     which is HIGH * 2**16 + LOW.
     The third element, MICROSEC, gives the microseconds since the
     start of the current second (or 0 for systems that return time
     only on the resolution of a second).
     The first two elements can be compared with file time values such
     as you get with the function `file-attributes'.  *Note File
     Attributes::.
 - Function: current-time-zone &optional TIME-VALUE
     This function returns a list describing the time zone that the
     user is in.
     The value has the form `(OFFSET NAME)'.  Here OFFSET is an integer
     giving the number of seconds ahead of UTC (east of Greenwich).  A
     negative value means west of Greenwich.  The second element, NAME
     is a string giving the name of the time zone.  Both elements
     change when daylight savings time begins or ends; if the user has
     specified a time zone that does not use a seasonal time
     adjustment, then the value is constant through time.
     If the operating system doesn't supply all the information
     necessary to compute the value, both elements of the list are
     `nil'.
     The argument TIME-VALUE, if given, specifies a time to analyze
     instead of the current time.  The argument should be a cons cell
     containing two integers, or a list whose first two elements are
     integers.  Thus, you can use times obtained from `current-time'
     (see above) and from `file-attributes' (*note File Attributes::.).